========================================================
  FROM THE SKIES — Installation Guide
  FIU KFSCIS Capstone II | Spring 2026
========================================================

This guide covers the normal installation and setup flow for building and
running From The Skies from source. It applies to developers and testers who
need to import the project, build it, and launch the NeoForge development
client or server.

========================================================
1. PREREQUISITES
========================================================

Install the following before opening the project:

  - Java Development Kit 21
  - Git
  - An IDE with Gradle support such as IntelliJ IDEA, Eclipse, or VS Code

This project already includes the Gradle wrapper, so a separate Gradle
installation is not required.

========================================================
2. CLONE THE REPOSITORY
========================================================

Open a terminal and run:

  git clone https://github.com/FT-Sun/FromTheSkies-1.21.X.git
  cd FromTheSkies-1.21.X

If you already have the repository locally, make sure you are on the branch
you want to build before continuing.

On Windows, replace ./gradlew with gradlew.bat for the commands in this guide.

========================================================
3. VERIFY THE JAVA VERSION
========================================================

Check that your shell is using Java 21:

  java -version

You should see a Java 21 runtime. If not, update your shell and IDE to use
JDK 21 before importing the project.

========================================================
4. OPEN THE PROJECT IN YOUR IDE
========================================================

Open the repository root as a Gradle project.

  IntelliJ IDEA:
    File > Open
    Select the repository root
    Allow Gradle import when prompted

  Eclipse:
    File > Import > Existing Gradle Project
    Select the repository root

  VS Code:
    Open the folder
    Allow the Java and Gradle extensions to import the workspace

========================================================
5. LET GRADLE SYNC AND DOWNLOAD DEPENDENCIES
========================================================

On first import, Gradle will download NeoForge, Minecraft mappings, and other
build dependencies. This can take several minutes.

If your IDE reports missing libraries or the import stalls, run:

  ./gradlew --refresh-dependencies

Windows:

  gradlew.bat --refresh-dependencies

========================================================
6. BUILD THE PROJECT
========================================================

Run a clean build from the repository root:

  ./gradlew build

Successful output will produce the mod JAR under:

  build/libs/

If you need to wipe generated build output and try again, run:

  ./gradlew clean build

========================================================
7. CONFIGURATION FILES
========================================================

There are two main configuration layers in this project.

(These are not needed to change for the mod to function as intended)

BUILD-TIME CONFIGURATION
------------------------

  gradle.properties
    Declares the Minecraft version, NeoForge version, mod ID, mod name,
    version, group ID, and Gradle JVM settings.
    Modify this when porting to a new version or changing project metadata.

  build.gradle
    Defines plugins, the Java 21 toolchain, NeoForge run profiles,
    publishing behavior, and generated metadata handling.
    Modify this when changing dependencies, repositories, run tasks, or
    build behavior.

  src/main/templates/META-INF/neoforge.mods.toml
    Template for mod metadata expanded during the build.
    Modify this when changing description text, authors, or dependency
    declarations.

RUNTIME CONFIGURATION
---------------------

  run/config/fromtheskiesmcmod-common.toml
    Main takeover configuration used in local development runs.
    Edit this when you want to enable or disable takeover, change timing,
    adjust spread speed, or allow different dimensions.

  run/config/neoforge-client.toml
    NeoForge client settings for the development runtime.

  run/config/neoforge-common.toml
    Shared NeoForge runtime settings.

  run/config/neoforge-server.toml
    NeoForge server runtime settings.

  run/config/fml.toml
    FML loader settings for the local run environment.

For a packaged client or dedicated server outside the development workspace,
the same mod config will live under that instance's config/ folder instead of
run/config/.

If fromtheskiesmcmod-common.toml does not exist yet, launch the client or
server once and NeoForge will generate it from Config.java.

========================================================
8. LAUNCH THE DEVELOPMENT CLIENT
========================================================

To start a client from source, run:

  ./gradlew runClient

This launches Minecraft with the mod loaded and uses the local run/ folder as
the game directory.

========================================================
9. REGENERATE DATA FILES WHEN NEEDED
========================================================

If you change datagen providers or content that feeds generated assets or data,
regenerate them with:

  ./gradlew runData

Generated output is written to:

  src/generated/resources/

========================================================
TROUBLESHOOTING
========================================================

  - If dependencies are missing, run:
      ./gradlew --refresh-dependencies

  - If generated files appear stale, run:
      ./gradlew clean runData

  - If the client fails to launch, confirm the project is using Java 21.

  - If the common TOML config file is missing, start the client or server once
    so NeoForge can generate it automatically.

========================================================
